docs/Inflight Adjustments.md

   1 # In-flight Adjustments
   2
   3 With INAV it's possible to make adjustments to various settings by using AUX channels from your transmitter while the aircraft is flying.
   4
   5 ## Warning
   6
   7 Changing settings during flight can make your aircraft unstable and crash if you are not careful.
   8
   9 ## Recommendations
  10
  11 * Always make adjustments while flying in a large open area.
  12 * Make small adjustments and fly carefully to test your adjustment.
  13 * Give yourself enough flying space and time to adjust to how your changes affect the behaviour of the aircraft.
  14 * Remember to set adjustment channel switches/pots to the center position before powering on your TX and your aircraft.
  15 * If possible configure switch warnings on your transitter for dedicated adjustment switches.
  16 * A momentary 3 position switch is the best choice of switch for this - i.e. one that re-centers itself when you let go of it.
  17
  18 ## Overview
  19
  20 Up to 4 RX channels can be used to make different adjustments at the same time.
  21
  22 The adjustment a channel makes can be controlled by another channel.
  23
  24 The following adjustments can be made, in flight, as well as on the ground.
  25
  26 * RC Rate
  27 * RC Expo
  28 * Throttle Expo
  29 * Roll & Pitch Rate
  30 * Yaw Rate
  31 * Pitch+Roll P I and D
  32 * Yaw P I and D
  33
  34 Example scenarios:
  35 Up to 4 3-position switches or pots can be used to adjust 4 different settings at the same time.
  36 A single 2/3/4/5/6/x position switch can be used to make one 3 position switch adjust one setting at a time.
  37
  38 Any combination of switches and pots can be used. So you could have 6 POS switch.
  39
  40 Settings are not saved automatically, connect a GUI, refresh and save or save using stick position when disarmed.
  41 Powering off without saving will discard the adjustments.
  42
  43 Settings can be saved when disarmed using stick positions: Throttle Low, Yaw Left, Pitch Low, Roll Right.
  44
  45 ## Adjustment switches
  46
  47 The switch can be a ON-OFF-ON, POT or momentary ON-OFF-ON switch.  The latter is recommended.
  48
  49 When the switch is returned to the center position the value will not be increased/decreased.
  50
  51 Each time you can press the switch high/low and then return it to the middle the value will change at least once, you do not have to wait before pressing the switch again if you want to increase/decrease at a faster rate.  While the adjustment switch held is high/low, the adjustment function applies and increases/decreases the value being adjusted twice a second and the flight controller will beep shorter/longer, respectively. The system works similar to how a keyboard repeat delay works.
  52
  53 Hint: With OpenTX transmitters you can combine two momentary OFF-ON switches to control a single channel.  You could make it so that a momentary switch on the left of your transmitter decreases the value and a momentary switch on the right increases the value.  Experiment with your mixer!
  54
  55
  56 ## Configuration
  57
  58 The CLI command `adjrange` is used to configure adjustment ranges.
  59
  60 12 adjustment ranges can be defined.
  61 4 adjustments can be made at the same time, each simultaneous adjustment requires an adjustment slot.
  62
  63 Show the current ranges using:
  64
  65 `adjrange`
  66
  67 Configure a range using:
  68
  69 `adjrange <index> <slot> <range channel> <range start> <range end> <adjustment function> <adjustment channel>`
  70
  71
  72
  73 | Argument | Value | Meaning |
  74 | -------- | ----- |-------- |
  75 | Index | 0 - 11 | Select the adjustment range to configure |
  76 | Slot | 0 - 3 | Select the adjustment slot to use |
  77 | Range Channel | 0 based index, AUX1 = 0, AUX2 = 1 | The AUX channel to use to select an adjustment for a switch/pot |
  78 | Range Start | 900 - 2100. Steps of 25, e.g. 900, 925, 950... | Start of range |
  79 | Range End | 900 - 2100 | End of range |
  80 | Adjustment function | 0 - 11 | See Adjustment function table |
  81 | Adjustment channel | 0 based index, AUX1 = 0, AUX2 = 1 | The channel that is controlled by a 3 Position switch/Pot |
  82
  83 Range Start/End values should match the values sent by your receiver.
  84
  85 Normally Range Channel and Slot values are grouped together over multiple adjustment ranges.
  86
  87 The Range Channel and the Adjustment Channel can be the same channel.  This is useful when you want a single 3 Position switch to be dedicated
  88 to a single adjustment function regardless of other switch positions.
  89
  90 The adjustment function is applied to the adjustment channel when range channel is between the range values.
  91 The adjustment is made when the adjustment channel is in the high or low position.  high = mid_rc + 200, low = mid_rc - 200.  by default this is 1700 and 1300 respectively.
  92
  93 When the Range Channel does not fall into Start/End range the assigned slot will retain it's state and will continue to apply the adjustment. For
  94 this reason ensure that you define enough ranges to cover the range channel's usable range.
  95
  96 ### Adjustment function
  97
  98 | Value | Adjustment | Notes |
  99 | ----- | ---------- |------ |
 100 | 0     | None |
 101 | 1     | RC RATE |
 102 | 2     | RC_EXPO |
 103 | 3     | THROTTLE_EXPO |
 104 | 4     | PITCH_ROLL_RATE |
 105 | 5     | YAW_RATE |
 106 | 6     | PITCH_ROLL_P |
 107 | 7     | PITCH_ROLL_I |
 108 | 8     | PITCH_ROLL_D |
 109 | 9     | YAW_P |
 110 | 10    | YAW_I |
 111 | 11    | YAW_D |
 112 | 12    | RATE_PROFILE | Switch between 3 rate profiles using a 3 position switch. |
 113 | 13    | PITCH_RATE |
 114 | 14    | ROLL_RATE |
 115 | 15    | PITCH_P |
 116 | 16    | PITCH_I |
 117 | 17    | PITCH_D |
 118 | 18    | ROLL_P |
 119 | 19    | ROLL_I |
 120 | 20    | ROLL_D |
 121
 122 ## Examples
 123
 124 ### Example 1 - 3 Position switch used to adjust pitch/roll rate
 125
 126 ```
 127 adjrange 0 0 3 900 2100 4 3
 128 ```
 129
 130 explained:
 131
 132 * configure adjrange 0 to use adjustment slot 1 (0) so that when aux4
 133 (3) in the range 900-2100 then use adjustment 4 (pitch/roll rate) when aux 4 (3)
 134 is in the appropriate position.
 135
 136
 137 ### Example 2 - 2 Position switch used to enable adjustment of RC rate via a 3 position switch
 138
 139 ```
 140 adjrange 1 1 0 900 1700 0 2
 141 adjrange 2 1 0 1700 2100 1 2
 142 ```
 143 explained:
 144
 145 * configure adjrange 1 to use adjustment slot 2 (1) so that when aux1
 146 (0) in the range 900-1700 then do nothing (0) when aux 3 (2) is in any
 147 position.
 148 * configure adjrange 2 to use adjustment slot 2 (1) so that when aux1
 149 (0) in the range 1700-2100 then use adjustment rc rate (1) when aux 3
 150 (2) is in the appropriate position.
 151
 152 Without the entire range of aux1 being defined there is nothing that
 153 would stop aux 3 adjusting the pitch/roll rate once aux 1 wasn't in the higher
 154 range.
 155
 156 ### Example 3 - 6 Position switch used to select PID tuning adjustments via a 3 position switch
 157
 158 ```
 159 adjrange 3 2 1 900 1150 6 3
 160 adjrange 4 2 1 1150 1300 7 3
 161 adjrange 5 2 1 1300 1500 8 3
 162 adjrange 6 2 1 1500 1700 9 3
 163 adjrange 7 2 1 1700 1850 10 3
 164 adjrange 8 2 1 1850 2100 11 3
 165 ```
 166
 167 explained:
 168
 169 * configure adjrange 3 to use adjustment slot 3 (2) so that when aux2
 170 (1) in the range 900-1150 then use adjustment Pitch/Roll P (6) when aux 4
 171 (3) is in the appropriate position.
 172 * configure adjrange 4 to use adjustment slot 3 (2) so that when aux2
 173 (1) in the range 1150-1300 then use adjustment Pitch/Roll I (7) when aux 4
 174 (3) is in the appropriate position.
 175 * configure adjrange 5 to use adjustment slot 3 (2) so that when aux2
 176 (1) in the range 1300-1500 then use adjustment Pitch/Roll D (8) when aux 4
 177 (3) is in the appropriate position.
 178 * configure adjrange 6 to use adjustment slot 3 (2) so that when aux2
 179 (1) in the range 1500-1700 then use adjustment Yaw P (9) when aux 4
 180 (3) is in the appropriate position.
 181 * configure adjrange 7 to use adjustment slot 3 (2) so that when aux2
 182 (1) in the range 1700-1850 then use adjustment Yaw I (10) when aux 4
 183 (3) is in the appropriate position.
 184 * configure adjrange 8 to use adjustment slot 3 (2) so that when aux2
 185 (1) in the range 1850-2100 then use adjustment Yaw D (11) when aux 4
 186 (3) is in the appropriate position.
 187
 188 ### Example 4 - Use a single 3 position switch to change between 3 different rate profiles
 189
 190 adjrange 11 3 3 900 2100 12 3
 191
 192 explained:
 193
 194 * configure adjrange 11 to use adjustment slot 4 (3) so that when aux4
 195 (3) in the range 900-2100 then use adjustment Rate Profile (12) when aux 4
 196 (3) is in the appropriate position.
 197
 198 When the switch is low, rate profile 0 is selcted.
 199 When the switch is medium, rate profile 1 is selcted.
 200 When the switch is high, rate profile 2 is selcted.
 201
 202
 203 ### Configurator examples
 204
 205 The following 5 images show valid configurations.  In all cales the enture usable range for the Range Channel is used.
 206
 207 ![Configurator example 1](Screenshots/adjustments-rate-profile-selection-via-3pos.png)
 208
 209 ---
 210
 211 ![Configurator example 2](Screenshots/adjustments-pitch-and-roll-rate-adjustment-via-3pos.png)
 212
 213 ---
 214
 215 ![Configurator example 3](Screenshots/adjustments-pid-via-two-3pos.png)
 216
 217 ---
 218
 219 ![Configurator example 4](Screenshots/adjustments-pid-via-6pos-and-3pos.png)
 220
 221 ---
 222
 223 ![Configurator example 5](Screenshots/adjustments-rates-via-a-2pos-and-3pos.png)
 224
 225 The following examples shows __incorrect__ configurations - the entire usable range for the Range Channel is not used in both cases.
 226
 227 ![Configurator example 6](Screenshots/adjustments-incorrect-config-1.png)
 228 ![Configurator example 7](Screenshots/adjustments-incorrect-config-2.png)
 229
 230 In the following example, the incorrect configuraton (above) has been corrected by adding a range that makes 'No changes'.
 231
 232 ![Configurator example 7](Screenshots/adjustments-incorrect-config-2-corrected.png)